.\" Copyright (c) 2010\-2012 Plowshare Team
.\"
.\" This is free documentation; you can redistribute it and/or
.\" modify it under the terms of the GNU General Public License as
.\" published by the Free Software Foundation; either version 3 of
.\" the License, or (at your option) any later version.
.\"
.\" The GNU General Public License's references to "object code"
.\" and "executables" are to be interpreted as the output of any
.\" document formatting or typesetting system, including
.\" intermediate and printed output.
.\"
.\" This manual is distributed in the hope that it will be useful,
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
.\" GNU General Public License for more details.
.\"
.\" You should have received a copy of the GNU General Public
.\" License along with this manual; if not, see
.\" <http://www.gnu.org/licenses/>.

.TH "plowup" "1" "June 30, 2012" "GPL" "Plowshare GIT-snapshot"

.SH NAME
plowup \- Command-line uploader for file-sharing websites

.SH SYNOPSIS
.B plowup
[\fIOPTIONS\fP]...
[\fIMODULE_OPTIONS\fP]...
\fIMODULE\fP
\fIURL\fP|\fIFILE\fP[\fI:DESTNAME\fP]...

.SH DESCRIPTION
.B plowup
is a set of bash scripts designed for automatic uploads on file-sharing website.
It acts like a web browser, retrieving pages and filling html forms (including captchas).

Currently supported hosting sites list is available in README file.

Anonymous upload is not allowed by all sites, some of them may require authentication.
See specific module options below.

.\" ****************************************************************************
.\" * Options                                                                  *
.\" ****************************************************************************
.SH OPTIONS

.SS Common options
.TP
.BI -i, " " --interface "=IFACE"
If your machine has several network interfaces, force using \fIIFACE\fR interface.
.TP
.BI "   " " " --max-rate "=SPEED"
Limit upload maximum speed in bytes per seconds. Suffixes are:
.RS 
\fBk\fR  for kilobytes (kB),
.RE
.RS
\fBm\fR  for megabytes (MB),
.RE
.RS
\fBg\fR  for gigabytes (GB).
.RE
.TP
.BI "   " " " --min-rate "=SPEED"
Limit upload minimum speed in bytes per seconds (for a delay of 30 seconds).
\fBK\fR (kibibyte) or \fBk\fR (kilobyte) suffixes can be specified.
.TP
.BI -t, " " --timeout "=SECS"
Cancel upload download after \fISECS\fR seconds of waits. Apply on module exit value: \fB10\fR (temporary unavailable error).
This error mainly occurs on remote upload operations.
Default option value is disabled (no timeout, infinite) and applies for one single upload.
.TP
.BI -r, " " --max-retries "=N"
Set maximum retries for upload failures. Apply on module exit value: \fB1\fR (fatal error), \fB3\fR (network error).
Default option value is 0 (no retry) and applies for one single upload.
.TP
.BI "   " " " --name-prefix "=STRING"
Prepend argument to each destination filename.
.TP
.BI "   " " " --name-suffix "=STRING"
Append argument to each destination filename.
.TP
.BI "   " " " --printf "=FORMAT"
Print results in a given format (for each upload). Default string is: \fI"%u (%D)"\fR. Interpreted sequences are:
.RS
.TP
\fI%%\fR
raw % character
.TP
\fI%a\fR
admin url or admin code
.TP
\fI%d\fR
delete url
.TP
\fI%D\fR
%d or %a (if %d is null string)
.TP
\fI%f\fR
destination (remote) filename
.TP
\fI%m\fR
module name
.TP
\fI%n\fR
newline
.TP
\fI%s\fR
filesize (in bytes)
.TP
\fI%t\fR
tabulation character
.TP
\fI%u\fR
download url
.RE
.SS Logging options
.TP
.BI -v, " " --verbose "=LEVEL"
Set output verbose level:
.RS 
\fB0\fR  none,
.RE
.RS 
\fB1\fR  errors,
.RE
.RS
\fB2\fR  notice (default behavior),
.RE
.RS
\fB3\fR  debug,
.RE
.RS
\fB4\fR  report (very noisy, log HTML pages).
.RE
.TP
.B -q, --quiet
Alias for \fB-v0\fR. Do not print any debug messages.
.SS Miscellaneous options
.TP
.B "   " --no-curlrc
Do not use curl config file (~/.curlrc).
.TP
.B "   " --no-plowsharerc
Do not use local or global config file (plowshare.conf).
.SS Generic program information
.TP
.B -h, --help
Display main help and exit.
.TP
.B -H, --longhelp
Display complete help (with module options) and exit.
.TP
.B "   " --version
Output version information and exit.

.\" ****************************************************************************
.\" * Modules options                                                          *
.\" ****************************************************************************
.SH "MODULE OPTIONS"

.SS Common options
.TP
.BI -a, " " --auth "=USER:PASSWORD"
Use premium account.
.TP
.BI -b, " " --auth-free "=USER:PASSWORD"
Use free account.
.TP
.BI -p, " " --link-password "=PASSWORD"
Protect your files with a password. May require premium account.
.TP
.BI -d, " " --description "=DESCRIPTION"
Set file description.
.TP
.BI "   " " " --email-from "=EMAIL"
<From> field for notification email.
.TP
.BI "   " " " --email-to "=EMAIL"
<To> field for notification email.
.P
All switches are not implemented nor required for all modules.
See long help message for detailed modules option list.

.\" ****************************************************************************
.\" * Examples                                                                 *
.\" ****************************************************************************
.SH EXAMPLES

.SS 1) Upload a single file anonymously
.nf
$ plowup bayfiles /tmp/foo.bar
.sp 1
# Add a text description
$ plowup \-d "Important document" megashares /path/myfile.tex
.sp 1
# Abort slow upload (if rate is below limit during 30 seconds)
$ plowup \-\-min\-rate 100k mediafire /path/bigfile.zip
.fi
.SS 2) Upload a single file with authentication
.nf
# Change destination filename
$ plowup \-a myuser:mypassword turbobit /path/myfile.txt:anothername.txt
.fi
.SS 3) Remote upload
URL fetching is rarely implemented by modules.

.nf
# Feature dedicated to premium members
$ plowup \-a myuser:mypassword oron http://www.somewherefarbeyond.com/somefile
.sp 1
# Change destination filename
$ plowup \-a myuser:mypassword oron http://www.somewherefarbeyond.com/somefile:anothername
.fi

.\" ****************************************************************************
.\" * Files                                                                    *
.\" ****************************************************************************
.SH "FILES"
.TP
.I ~/.config/plowshare/plowshare.conf
This is the per-user configuration file. 
.TP
.I /etc/plowshare.conf
Systemwide configuration file.
.PP
The file format is described in
.BR plowshare.conf (5).

.\" ****************************************************************************
.\" * Exit codes                                                               *
.\" ****************************************************************************
.SH "EXIT CODES"

Possible exit codes are: 
.IP 0 
Success.
.IP 1
Fatal error. Upstream site updated or unexpected result.
.IP 2
No available module (provided module name does not exist).
.IP 3
Network error. Mostly curl related.
.IP 4
Authentication failed (bad login/password).
.IP 5
Timeout reached (refer to \fI-t/--timeout\fP command-line option).
.IP 6
Maximumn tries reached (refer to \fI-r/--max-retries\fP command-line option).
.IP 8
System generic error.
.IP 10
Feature (upload service) seems temporarily unavailable from upstream.
.IP 12
Authentication required (example: anonymous users can't do remote upload).
.IP 14
Can't upload too big file (need permissions).
.IP 15
Unknown command line parameter or incompatible options.
.PP
If
.B plowup
is invoked with multiple files and one or several errors occur, the first error code is returned added with 100.

.\" ****************************************************************************
.\" * Authors / See Also                                                       *
.\" ****************************************************************************
.SH AUTHORS
Plowshare was initially written by Arnau Sanchez. See the AUTHORS file for a list of some of the many other contributors.

Plowshare is (C) 2010-2012 The Plowshare Team
.SH "SEE ALSO"
.BR plowdown (1),
.BR plowdel (1),
.BR plowlist (1),
.BR plowshare.conf (5).
